<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
    <title>JavaScripTools Manual</title>
    <link rel="stylesheet" type="text/css" href="../../css/style.css">
</head>

<body>
<br>
<h1>JavaScripTools Manual</h1>
<h2>InputMask</h2>
<h3>Working with the InputMask</h3>
<p>InputMask is a general-purpose mask. It can restrict wich characters
can be typed, restrict size and apply case transformations. If you want to mask numbers and dates,
please, consider using <a href="InputMask_number.html">NumberMask</a> and
<a href="InputMask_date.html">DateMask</a> instead, because they are specific to these data
types and offers specific and richer features.</p>
<p>The mask is composed of one or more fields. Each field can be a literal
or an input, and can apply an specific case transformation. A mask that accepts
only numbers, allowing a maximum of 5 digits has a single field, that accepts numbers 
and limits the size to 5. A mask like ##/AA is composed of 3 fields: 2 numbers, a literal '/'
and 2 letters.</p>
<p>Each field is a subclass of the <a href="../api/class_MaskField.html">MaskField</a> class, and can be 
one of the following classes:<ul>
    <li><a href="../api/class_Literal.html">Literal</a>: Is a fixed string literal. Receives the string on the constructor</li>
    <li><a href="../api/class_Inputd.html">Input</a>: Is a typeable field. Receives a string containing the accepted characters. null means any character</li>
    <li><a href="../api/class_Lower.html">Lower</a>: An Input that transforms the text to lowercase</li>
    <li><a href="../api/class_Upper.html">Upper</a>: An Input that transforms the text to uppercase</li>
    <li><a href="../api/class_Capitalize.html">Capitalize</a>: An Input that capitalizes the text</li>
</ul></p>
<p>The <code>MaskField</code> was called <code>Field</code> on previous versions, but has been renamed to enable compatibility
with the excellent <a href="http://prototype.conio.net">Prototype Framework</a>, that already has a class named <code>Field</code>.</p>
<p>There are higher-level ways of constructing the mask fields. The <a href="../api/class_FieldBuilder.html">FieldBuilder</a>
and <a href="../api/class_MaskBuilder.html">MaskBuilder</a> classes offers methods to do this. There are default instanced for
both of these classes declared that you can use: fieldBuilder and maskBuilder.</p>
<p>The InputMask first constructor argument is a field, a field array or a string. When it's a string, the
<a href="../api/class_MaskBuilder.html#parse">MaskBuilder.parse</a> method is called. It will parse the string, recognizing the following characters:
<table cellspacing="0" border="1" width="100%">
    <tr>
        <td>#, 0 or 9</td>
        <td>A number</td>
    </tr>
    <tr>
        <td>a or A</td>
        <td>A letter</td>
    </tr>
    <tr>
        <td>? or _</td>
        <td>Any character</td>
    </tr>
    <tr>
        <td>l or L</td>
        <td>A lowercase letter</td>
    </tr>
    <tr>
        <td>u or U</td>
        <td>An uppercase letter</td>
    </tr>
    <tr>
        <td>c or C</td>
        <td>A capitalized letter</td>
    </tr>
    <tr>
        <td>\\, \#, \0, ...</td>
        <td>Those literal characters. Remember that, when you write a string, '\\' means a single backslask. To use a backslash on the mask, you need 4 on the string.</td>
    </tr>
    <tr>
        <td>Any other character</td>
        <td>Literal characters</td>
    </tr>
</table>
</p>
<p>The second constructor argument is the control name or reference. The next arguments are
custom event handlers, and not recommended as constructor arguments, but as properties.
For more information about custom event handlers, check the 
<a href="InputMask_intro.html">introduction</a>.</p>
<p>Here are some examples:</p>
<pre>//Accept only alpha, using the Input constructor
var mask = new InputMask(new Input(JST_CHARS_BASIC_ALPHA), "myControl");

//Accept only letters and spaces, and applying capitalization, using the fieldBuilder
var mask = new InputMask(fieldBuilder.capitalize(JST_CHARS_LETTERS + " "), "customerName");

//A custom mask, for 3 numbers, a slash and 2 uppercase letters
var mask = new InputMask("###/UU", "customField");

//A custom mask, for 3 numbers, a forward slash and 2 uppercase letters
var mask = new InputMask("###\\\\UU", "customField");

//Apply a custom event handler for onkeypress event
mask.keyPressFunction = function(event, mask) {
    setValue("output", "My new value is " + mask.control.value);
}
</pre>
<p><b>Note for Internet Explorer</b>: To use a mask on a textarea in Internet Explorer, the mask must have a single field,
only with a set of allowed input, without case transformations and without size limit.</p>
<br>
<a name="padding"></a>
<h4>Padding</h4>
<p>Another, more advanced field function is called padding. Each field can have an associated
function that can be used to complete the field value. The function receives the text, the minumim 
size and the maximum size. By contract, this function should always return a text with matches those
size constraints (remember max = -1 means no limit).
There is always a default pad function if none was informed (it uses the 
<a href="../api/JavaScriptUtil_functions.html#lpad">lpad</a> and 
<a href="../api/JavaScriptUtil_functions.html#left">left</a> functions to enforce the text size).
Custom masks rarely will have custom padding.</p>
<p>Padding is triggered on the following events: <ul>
<li>The user types the first letter of the next literal field</li>
<li>On the control onblur event, the last field is padded</li>
<li>The user forces pad by typing ctrl + Enter or ctrl + Right</li></ul></p>
<p>Examples on custom padding:</p>
<pre>function myPadding(text, min, max) {
    setValue("out", text)
    switch (text.toLowerCase()) {
        case "m": return "Male";
        case "f": return "Female";
        default: return text;
    }
}
var mask = new InputMask(fieldBuilder.inputLetters(0, -1, myPadding), "myControl");
//If the user types "m" and leaves the field, the field value becomes "Male"
</pre>
<br><br>
<hr>
<table width="100%">
    <tr>
        <td width="33%" align="left"><b>Previous:</b><br><a href="InputMask_intro.html">Introduction to InputMask</a></td>
        <td width="34%" align="center"><a href="index.html">Table of Contents</a></td>
        <td width="33%" align="right"><b>Next:</b><br><a href="InputMask_number.html">Working with the NumberMask</a></td>
    </tr>
</table>

</body>
</html>
